home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.1 / Amiga Developer CD v1.1 - May 1996 (1996)(Schatztruhe)[!].iso / Contributions / IAM / Networking / Envoy-2.0 / doc / nipc.doc < prev    next >
Text File  |  1994-12-22  |  51KB  |  1,545 lines
  1. TABLE OF CONTENTS
  2.  
  3. nipc.library/AbortTransaction
  4. nipc.library/AddRoute
  5. nipc.library/AllocNIPCBuff
  6. nipc.library/AllocNIPCBuffEntry
  7. nipc.library/AllocTransactionA
  8. nipc.library/AppendNIPCBuff
  9. nipc.library/BeginTransaction
  10. nipc.library/CheckTransaction
  11. nipc.library/CopyFromNIPCBuff
  12. nipc.library/CopyNIPCBuff
  13. nipc.library/CopyToNIPCBuff
  14. nipc.library/CreateEntityA
  15. nipc.library/DeleteEntity
  16. nipc.library/DeleteRoute
  17. nipc.library/DoTransaction
  18. nipc.library/FindEntity
  19. nipc.library/FreeNIPCBuff
  20. nipc.library/FreeNIPCBuffEntry
  21. nipc.library/FreeTransaction
  22. nipc.library/GetEntityAttrsA
  23. nipc.library/GetEntityName
  24. nipc.library/GetHostName
  25. nipc.library/GetTransaction
  26. nipc.library/LoseEntity
  27. nipc.library/NIPCBuffLength
  28. nipc.library/NIPCBuffPointer
  29. nipc.library/NIPCInquiryA
  30. nipc.library/PingEntity
  31. nipc.library/ReplyTransaction
  32. nipc.library/SetEntityAttrsA
  33. nipc.library/WaitEntity
  34. nipc.library/WaitTransaction
  35. nipc.library/AbortTransaction                   nipc.library/AbortTransaction
  36.  
  37.    NAME
  38.      AbortTransaction -- Abort an attempted transaction.
  39.  
  40.    SYNOPSIS
  41.      AbortTransaction(transaction)
  42.                           A1
  43.  
  44.      VOID AbortTransaction(struct Transaction *);
  45.  
  46.    FUNCTION
  47.      Aborts a Transaction that was previously started by a call to
  48.      BeginTransaction().
  49.  
  50.    INPUTS
  51.      transaction - Pointer to the Transaction to abort.
  52.  
  53.    RESULT
  54.      If the transaction hadn't already been completed (or failed), it will
  55.      be immediately aborted, and placed on the local Entity.
  56.  
  57.    EXAMPLE
  58.  
  59.    NOTES
  60.      Because local Transactions are passed by reference, a transaction
  61.      sent to a local Entity can be in such a state (being processed)
  62.      where another process may be referencing them.  To ensure that
  63.      a Transaction is either aborted or completed, an AbortTransaction()
  64.      call should be followed by a WaitTransaction().  If the transaction
  65.      given has already completed (or failed), no action will be taken.
  66.  
  67.    BUGS
  68.  
  69.    SEE ALSO
  70.      WaitTransaction(), DoTransaction(), BeginTransaction(),
  71.      CheckTransaction()
  72.  
  73. nipc.library/AddRoute                                   nipc.library/AddRoute
  74.  
  75.    NAME
  76.      AddRoute -- Add a route/gateway for a network
  77.  
  78.    SYNOPSIS
  79.        success = AddRoute(network,gateway,hops,ttl)
  80.           d0                d0      d1     d2  d3
  81.  
  82.        BOOL AddRoute(ULONG,ULONG,UWORD,WORD);
  83.  
  84.    FUNCTION
  85.      Adds a route for a given network to NIPC's routing tables.  Gateway
  86.      tells NIPC what gateway to use for that network, and hops is the
  87.      maximum number of hops to use to get to the network.  'ttl' is
  88.      'time to live' for the route.  This parameter is currently ignored,
  89.      and -1 must be passed for ttl.
  90.  
  91.    INPUTS
  92.      network - network number this route is for
  93.      gateway - the gateway machine on that knows how to talk to 'network'
  94.      hops    - maximum number of hops for packets going to 'network'
  95.      ttl     - time to live.  Must currently be set to -1.
  96.  
  97.    RESULT
  98.      success - true for success, false for failure to add the route.
  99.  
  100.    EXAMPLE
  101.  
  102.    NOTES
  103.  
  104.    BUGS
  105.  
  106.    SEE ALSO
  107.        DeleteRoute()
  108.  
  109. nipc.library/AllocNIPCBuff                         nipc.library/AllocNIPCBuff
  110.  
  111.    NAME
  112.      AllocNIPCBuff -- Allocate and initialize a NIPCBuff structure
  113.  
  114.    SYNOPSIS
  115.      nipcbuff = AllocNIPCBuff(entries)
  116.      D0                       D0
  117.  
  118.      struct NIPCBuff *AllocNIPCBuff(entries);
  119.  
  120.    FUNCTION
  121.      This function is used to allocate an NIPCBuff structure for use with
  122.      transaction data areas.  Note that this function only allocates the
  123.      NIPCBuff structure, initializes it, and possibly adds a number of
  124.      NIPCBuffEntry's to it.  No data area is allocated.
  125.  
  126.    INPUTS
  127.      entries - The number of NIPCBuffEntry's that should be placed in the
  128.                NIPCBuff structure.
  129.  
  130.    RESULT
  131.      nipcbuff - Pointer to a newly allocated and initialized NIPCBuff
  132.                 structure or NULL if the NIPCBuff or the number of
  133.                 NIPCBuffEntry structures couldn't be allocated.
  134.  
  135.    EXAMPLE
  136.  
  137.    NOTES
  138.      You MUST use this function for allocating NIPCBuff structures, or
  139.      innocent memory will get overwritten.
  140.  
  141.    BUGS
  142.  
  143.    SEE ALSO
  144.        FreeNIPCBuff(), <envoy/nipc.h>
  145.  
  146. nipc.library/AllocNIPCBuffEntry               nipc.library/AllocNIPCBuffEntry
  147.  
  148.    NAME
  149.      AllocNIPCBuffEntry -- Allocate and initialize a NIPCBuffEntry structure
  150.  
  151.    SYNOPSIS
  152.      entry = AllocNIPCBuffEntry()
  153.      D0
  154.  
  155.      struct NIPCBuffEntry *AllocNIPCBuffEntry();
  156.  
  157.    FUNCTION
  158.      This function is used to allocate an NIPCBuffEntry structure for use
  159.      with NIPCBuff structures. Note that this function only allocates the
  160.      NIPCBuffEntry structure, and clears it.  No data area is allocated.
  161.  
  162.    INPUTS
  163.      None
  164.  
  165.    RESULT
  166.      entry - Pointer to a newly allocated and initialized NIPCBuffEntry
  167.              structure or NULL if the NIPCBuffEntry couldn't be allocated.
  168.  
  169.    EXAMPLE
  170.  
  171.    NOTES
  172.      You MUST use this function for allocating NIPCBuffEntry structures, or
  173.      innocent memory will get overwritten.
  174.  
  175.    BUGS
  176.  
  177.    SEE ALSO
  178.        FreeNIPCBuffEntry(), <envoy/nipc.h>
  179.  
  180. nipc.library/AllocTransactionA                 nipc.library/AllocTransactionA
  181.  
  182.    NAME
  183.      AllocTransactionA -- Allocate a transaction structure.
  184.  
  185.    SYNOPSIS
  186.      transaction = AllocTransactionA(taglist)
  187.         D0                             A0
  188.  
  189.      struct Transaction *AllocTransactionA(struct TagItem *);
  190.      struct Transaction *AllocTransaction(tag1, tag2, tag3, ...);
  191.  
  192.    FUNCTION
  193.      This function will attempt to create a Transaction structure
  194.      for the user.
  195.  
  196.    INPUTS
  197.      taglist -- A pointer to a list of tags defining options and requirements
  198.                 for the structure.
  199.  
  200.                 TRN_AllocReqBuffer:
  201.                  Attempts to allocate a request buffer for you of the
  202.                  size in the ti_Data field of this TagItem.
  203.                  (default: no request buffer)
  204.                 TRN_AllocRespBuffer:
  205.                  Attempts to allocate a response buffer for you of the
  206.                  size in the ti_Data field of this TagItem.
  207.                  (default: no response buffer)
  208.                 TRN_ReqDataNIPCBuff:
  209.                 TRN_RespDataNIPCBuff:
  210.                  These Tags are used to tell nipc.library that either
  211.                  trans_ResponseData or trans_RequestData are pointers
  212.                  to NIPCBuff structures.  "Normal" programmers won't
  213.                  need to use this feature.
  214.  
  215.                 A NULL taglist will yield the defaults which are no
  216.                 allocations and no NIPCBuff structures.
  217.  
  218.    RESULT
  219.      transaction -- If conditions permit, AllocTransaction() will return
  220.                     a pointer to a Transaction structure.  If the library is
  221.                     unable to either allocate memory or meet the requirements
  222.                     set by the tags passed, the function will return a NULL.
  223.  
  224.    EXAMPLE
  225.  
  226.    NOTES
  227.                 You are completely free to allocate your own buffer space
  228.                 for either a request or a response buffer.  If done, you
  229.                 are also responsible for freeing them.
  230.  
  231.    BUGS
  232.  
  233.    SEE ALSO
  234.  
  235. nipc.library/AppendNIPCBuff                       nipc.library/AppendNIPCBuff
  236.  
  237.    NAME
  238.      AppendNIPCBuff -- Append one NIPCBuff structure to another
  239.  
  240.    SYNOPSIS
  241.      result = AppendNIPCBuff(first, second)
  242.      D0                      A0     A1
  243.  
  244.      struct NIPCBuff *AppendNIPCBuff(struct NIPCBuff *, struct NIPCBuff *);
  245.  
  246.    FUNCTION
  247.      This function may be used to append the data in one NIPCBuff to another
  248.      NIPCBuff.  Essentially, it just removes the NIPCBuffEntry's from
  249.      one NIPCBuff and adds them to the other NIPCBuff (in order).
  250.  
  251.      After this function completes, the second NIPCBuff will be empty.
  252.  
  253.    INPUTS
  254.      first- Pointer to the NIPCBuf structure to be appended to.
  255.      second - Pointer to the NIPCBuff structure to be appended.
  256.  
  257.    RESULT
  258.      result - Pointer to the first NIPCBuff
  259.  
  260.    EXAMPLE
  261.  
  262.    NOTES
  263.  
  264.    BUGS
  265.  
  266.    SEE ALSO
  267.      <envoy/nipc.h>
  268.  
  269. nipc.library/BeginTransaction                   nipc.library/BeginTransaction
  270.  
  271.    NAME
  272.      BeginTransaction -- Start an NIPC Transaction
  273.  
  274.    SYNOPSIS
  275.      BeginTransaction(dest_entity,src_entity, transaction)
  276.                          A0          A1          A2
  277.  
  278.      VOID BeginTransaction(struct Entity *,struct Entity *,
  279.                            struct Transaction *);
  280.  
  281.    FUNCTION
  282.      Attempts to begin a transaction (described appropriately by the
  283.      transaction structure) to a given entity.
  284.  
  285.    INPUTS
  286.      dest_entity - An abstract data type - a "magic cookie" - that identifies
  287.                    the destination entity.  (From FindEntity().)
  288.      src_entity  - An abstract data type - a "magic cookie" - that identifies
  289.                    the source entity.  (From CreateEntity().)
  290.      transaction - a pointer to the Transaction to start.
  291.  
  292.    RESULT
  293.      None.
  294.  
  295.    EXAMPLE
  296.  
  297.    NOTES
  298.      After this function begins, the Transaction structure passed becomes
  299.      the property of the nipc.library, and CANNOT be freed until this
  300.      Transaction returns to the source Entity.  Once the Transaction
  301.      returns onto the local Entity, the programmer should check
  302.      trans_Error, to verify that it completed properly.
  303.  
  304.      Because data transmission isn't an instantaneous operation,
  305.      a limit must be imposed on exactly how many transactions
  306.      can be queued up at any given time.  Otherwise, it would be possible
  307.      for an application program to overflow the throughput of any given
  308.      networking protocol, occupying all available memory.  If the
  309.      underlying networking protocol becomes overloaded, subsequent
  310.      calls to BeginTransaction() may block until the networking
  311.      protocol is no longer overwhelmed.
  312.  
  313.    BUGS
  314.  
  315.    SEE ALSO
  316.        DoTransaction(), CheckTransaction(), WaitTransaction(),
  317.        AbortTransaction(), <envoy/nipc.h>
  318.  
  319. nipc.library/CheckTransaction                   nipc.library/CheckTransaction
  320.  
  321.    NAME
  322.      CheckTransaction -- Check whether a transaction has completed or not.
  323.  
  324.    SYNOPSIS
  325.      status = CheckTransaction(transaction);
  326.        D0                          A1
  327.  
  328.      BOOL CheckTransaction(struct Transaction *);
  329.  
  330.    FUNCTION
  331.      Provides a mechanism for determining whether a Transaction previously
  332.      queued with BeginTransaction() has completed.  The function
  333.      will return TRUE if the Transaction is complete (or failed), and FALSE
  334.      if the Transaction is still in progress.
  335.  
  336.    INPUTS
  337.      transaction - a pointer to a Transaction structure, which describes
  338.                    the details of this specific Transaction.
  339.  
  340.    RESULT
  341.      None.
  342.  
  343.    EXAMPLE
  344.  
  345.    NOTES
  346.        CheckTransaction() will return TRUE if the Transaction has never
  347.        been sent (unlike CheckIO(), which doesn't take this situation
  348.        into account).
  349.  
  350.    BUGS
  351.  
  352.    SEE ALSO
  353.        DoTransaction(), BeginTransaction(), WaitTransaction(),
  354.        AbortTransaction()
  355.  
  356. nipc.library/CopyFromNIPCBuff                   nipc.library/CopyFromNIPCBuff
  357.  
  358.    NAME
  359.      CopyFromNIPCBuff -- Copy block of memory out of a NIPCBuff structure
  360.  
  361.    SYNOPSIS
  362.      actual = CopyFromNIPCBuff(src, dest, srcoffset, length)
  363.      D0                        A0   A1    D0         D1
  364.  
  365.      ULONG CopyFromNIPCBuff(struct NIPCBuff *, UBYTE *, ULONG, ULONG);
  366.  
  367.    FUNCTION
  368.      This function is used to copy one NIPCBuff to another.  The number of
  369.      bytes actually copied will be returned.  If there isn't enough space
  370.      in the destination buffer, then actual will be less than length.
  371.  
  372.    INPUTS
  373.      src - Pointer to the NIPCBuf structure to be copied from.
  374.      dest - Pointer to the NIPCBuff structure to be copied to.
  375.      dstoffset - Offset into dest buffer.
  376.      length - Number of bytes to copy.
  377.  
  378.    RESULT
  379.      actual - Number of bytes actually copied.
  380.  
  381.    EXAMPLE
  382.  
  383.    NOTES
  384.      This function does not modify any of the fields in the destination
  385.      NIPCBuff structure or its NIPCBuffEntries.  It will abide by the
  386.      existing values of nbe_Offset and nbe_Length.
  387.  
  388.      The upshot of this is that if you want the entire data area referenced
  389.      by a NIPCBuffEntry to be copied to, you should do the following:
  390.  
  391.      ...
  392.      nbe->nbe_Offset = 0;
  393.      nbe->nbe_Length = nbe->nbe_PhysicalLength;
  394.      ...
  395.  
  396.  
  397.    BUGS
  398.  
  399.      Before version 40.7, this function may not work correctly due to a
  400.      bug in NIPCBuffPointer, except when the source offset is zero.
  401.  
  402.    SEE ALSO
  403.      <envoy/nipc.h>
  404.  
  405. nipc.library/CopyNIPCBuff                           nipc.library/CopyNIPCBuff
  406.  
  407.    NAME
  408.      CopyNIPCBuff -- Copy a NIPCBuff structure
  409.  
  410.    SYNOPSIS
  411.      actual = CopyNIPCBuff(src, dest, srcoffset, dstoffset, length)
  412.      D0                    A0   A1    D0         D1         D2
  413.  
  414.      ULONG CopyNIPCBuff(struct NIPCBuff *, struct NIPCBuff *,
  415.                         ULONG, ULONG, ULONG);
  416.  
  417.    FUNCTION
  418.      This function is used to copy one NIPCBuff to another.  The number of
  419.      bytes actually copied will be returned.  If there isn't enough space
  420.      in the destination buffer, then actual will be less than length.
  421.  
  422.    INPUTS
  423.      src - Pointer to the NIPCBuf structure to be copied from.
  424.      dest - Pointer to the NIPCBuff structure to be copied to.
  425.      srcoffset - Offset into src buffer.
  426.      dstoffset - Offset into dest buffer.
  427.      length - Number of bytes to copy.
  428.  
  429.    RESULT
  430.      actual - Number of bytes actually copied.
  431.  
  432.    EXAMPLE
  433.  
  434.    NOTES
  435.      This function does not modify any of the fields on the src or data
  436.      NIPCBuff structures or their NIPCBuffEntries.  It will abide by
  437.      the current values of nbe_Offset and nbe_Length on both the source
  438.      and desitnation buffers.
  439.  
  440.      The upshot of this is that if you want the entire data area referenced
  441.      by a NIPCBuffEntry to be copied from/to, you should do the following:
  442.  
  443.      ...
  444.      nbe->nbe_Offset = 0;
  445.      nbe->nbe_Length = nbe->nbe_PhysicalLength;
  446.      ...
  447.  
  448.  
  449.    BUGS
  450.  
  451.      Before version 40.7, this function may not work correctly due to a
  452.      bug in NIPCBuffPointer, except when both source and destination offsets
  453.      are zero.
  454.  
  455.    SEE ALSO
  456.      <envoy/nipc.h>
  457.  
  458. nipc.library/CopyToNIPCBuff                       nipc.library/CopyToNIPCBuff
  459.  
  460.    NAME
  461.      CopyToNIPCBuff -- Copy block of memory into a NIPCBuff structure
  462.  
  463.    SYNOPSIS
  464.      actual = CopyToNIPCBuff(src, dest, dstoffset, length)
  465.      D0                      A0   A1    D0         D1
  466.  
  467.      ULONG CopyToNIPCBuff(UBYTE *, struct NIPCBuff *, ULONG, ULONG);
  468.  
  469.    FUNCTION
  470.      This function is used to copy data from a block of memory into a
  471.      NIPCBuff.  If there isn't enough space in the destination buffer,
  472.      then actual will be less than length.
  473.  
  474.    INPUTS
  475.      src - Pointer to the block of memory to be copied from.
  476.      dest - Pointer to the NIPCBuff structure to be copied to.
  477.      dstoffset - Offset into destination buffer.
  478.      length - Number of bytes to copy.
  479.  
  480.    RESULT
  481.      actual - Number of bytes actually copied.
  482.  
  483.    EXAMPLE
  484.  
  485.    NOTES
  486.      This function does not modify any of the fields in the destination
  487.      NIPCBuff structure or its NIPCBuffEntries.  It will abide by the
  488.      existing values of nbe_Offset and nbe_Length.
  489.  
  490.      The upshot of this is that if you want the entire data area referenced
  491.      by a NIPCBuffEntry to be copied to, you should do the following:
  492.  
  493.      ...
  494.      nbe->nbe_Offset = 0;
  495.      nbe->nbe_Length = nbe->nbe_PhysicalLength;
  496.      ...
  497.  
  498.  
  499.    BUGS
  500.  
  501.      Before version 40.7, this function may not work correctly due to a
  502.      bug in NIPCBuffPointer, except when the destination offset is zero.
  503.  
  504.    SEE ALSO
  505.      <envoy/nipc.h>
  506.  
  507. nipc.library/CreateEntityA                         nipc.library/CreateEntityA
  508.  
  509.    NAME
  510.      CreateEntityA -- Creates an Entity for communication.
  511.  
  512.    SYNOPSIS
  513.      myentity = CreateEntityA(taglist)
  514.         D0                      A0
  515.  
  516.      struct Entity *CreateEntityA(struct TagItem *);
  517.      struct Entity *CreateEntity(tag1, tag2, tag3, ...);
  518.  
  519.    FUNCTION
  520.      This function allows you to create an Entity for one endpoint
  521.      for communication.  Given the appropriate tags, you may declare that
  522.      this entity is public - and therefore can be located by FindEntity().
  523.  
  524.    INPUTS
  525.      taglist -- a list of tags that declare items such as the Entity name
  526.                 (which is only necessary for public Entities), signal
  527.                 bits, etc.
  528.  
  529.                 The following tags are defined:
  530.                 ENT_Name:
  531.                  Allows the user to declare the name for this entity.  This
  532.                  name must be unique -- and if an Entity of similar name
  533.                  already exists, CreateEntity() will return NULL.
  534.                  (default: no provided name)
  535.                 ENT_Public:
  536.                  If included, this entity is _public_, and can be found
  537.                  by FindEntity() call.  To declare an entity public,
  538.                  you must also declare the entity name.
  539.                  (default: private)
  540.                 ENT_Signal:
  541.                  Defines that when something arrives at this entity,
  542.                  the given signal bit (bit number, not mask) should
  543.                  be set.  (Useful when you intend to maintain a LOT
  544.                  of entities - more than possible to allocate a single
  545.                  signal bit for each.  In this method, a large number
  546.                  of entities share the signal bit.  The downside is that
  547.                  every entity with that bit must be checked when
  548.                  the bit is found set.)
  549.                  (default: FALSE)
  550.                 ENT_AllocSignal:
  551.                  Asks that CreateEntity() allocate a signal bit from
  552.                  the current context, and set it whenever the
  553.                  entity receives any data, to set that bit.  The
  554.                  ti_Data field of this TagItem must be a pointer
  555.                  to a ULONG which CreateEntity will fill in with the
  556.                  bit number, such that you know what bit number to
  557.                  Wait() on.  If you provide a NULL as the ti_Data
  558.                  entry, you will not be informed of the signal bit
  559.                  number.
  560.                  (default: signal not allocated)
  561.  
  562.                  A NULL taglist will provide the defaults.
  563.  
  564.    RESULT
  565.      entity  --  a 'magic cookie' that defines your entity, or NULL for
  566.                  failure
  567.  
  568.    EXAMPLE
  569.  
  570.    NOTES
  571.      ENT_Signal and ENT_AllocSignal are mutually exclusive.
  572.      ENT_Public requires that you also provide ENT_Name; the
  573.        converse, however, is not true.
  574.  
  575.    BUGS
  576.  
  577.    SEE ALSO
  578.      DeleteEntity()
  579.  
  580. nipc.library/DeleteEntity                           nipc.library/DeleteEntity
  581.  
  582.    NAME
  583.      DeleteEntity -- Delete an Entity
  584.  
  585.    SYNOPSIS
  586.      DeleteEntity(entity);
  587.                     A0
  588.  
  589.      VOID DeleteEntity(struct Entity *);
  590.  
  591.    FUNCTION
  592.      DeleteEntity() is the converse of CreateEntity().  It removes the
  593.      entity from NIPC lists that it may have been attached to,
  594.      frees up any resources attached to this Entity that were
  595.      allocated by CreateEntity(), and frees up the actual Entity
  596.      structure.  If NULL is passed as the argument, no action will
  597.      be taken.
  598.  
  599.    INPUTS
  600.      entity  --  a 'magic cookie' that defines your Entity
  601.  
  602.    RESULT
  603.      None.
  604.  
  605.    EXAMPLE
  606.  
  607.    NOTES
  608.      If an attempt is made to DeleteEntity() an Entity that has been
  609.      found (via FindEntity()), but not lost (via LoseEntity()),
  610.      the Entity being deleted will be maintained by NIPC until
  611.      all references to it no longer exist.
  612.      (The same behavior should arguably occur for an Entity on which
  613.      previously sent Transactions are yet to return.)
  614.  
  615.      IMPORTANT WARNING:
  616.      Use DeleteEntity() ONLY on Entities created with CreateEntity().
  617.      Do NOT use DeleteEntity() on Entities created with FindEntity()!!
  618.  
  619.    BUGS
  620.  
  621.    SEE ALSO
  622.      CreateEntityA(), LoseEntity()
  623.  
  624. nipc.library/DeleteRoute                             nipc.library/DeleteRoute
  625.  
  626.    NAME
  627.      DeleteRoute -- Remove a route/gateway for a network
  628.  
  629.    SYNOPSIS
  630.        DeleteRoute(network)
  631.                      d0
  632.  
  633.        VOID DeleteRoute(ULONG);
  634.  
  635.    FUNCTION
  636.      Removes a route for a given network from NIPC's routing tables.
  637.  
  638.    INPUTS
  639.      network - network number to remove the route for
  640.  
  641.    RESULT
  642.  
  643.    EXAMPLE
  644.  
  645.    NOTES
  646.  
  647.    BUGS
  648.  
  649.    SEE ALSO
  650.        AddRoute()
  651.  
  652. nipc.library/DoTransaction                         nipc.library/DoTransaction
  653.  
  654.    NAME
  655.      DoTransaction -- Begin a Transaction, and wait for it to complete.
  656.  
  657.    SYNOPSIS
  658.      DoTransaction(dest_entity,src_entity,transaction)
  659.                      A0            A1          A2
  660.  
  661.      VOID DoTransaction(struct Entity *, struct Entity *,
  662.                         struct Transaction *);
  663.  
  664.    FUNCTION
  665.      Processes an entire Transaction; it sends the request to the host
  666.      Entity and awaits the response, or returns at any point because
  667.      of an error.
  668.  
  669.    INPUTS
  670.      dest_entity - An abstract data type - a "magic cookie" - that identifies
  671.                    the destination entity.  (From FindEntity().)
  672.      src_entity  - An abstract data type - a "magic cookie" - that identifies
  673.                    the destination entity.  (From CreateEntity().)
  674.      transaction - a pointer to the Transaction to complete.
  675.  
  676.    RESULT
  677.      None.
  678.  
  679.    EXAMPLE
  680.  
  681.    NOTES
  682.      DoTransaction() causes the current context to go into
  683.      a Wait() state until the Transaction is complete (or cannot be
  684.      completed.  After a DoTransaction() call, the trans_Error
  685.      field should be checked to verify that the Transaction was
  686.      properly completed.
  687.  
  688.      DoTransaction(), like WaitTransaction() is potentially dangerous, and
  689.      should be used carefully.  If no trans_Timeout value is included,
  690.      and a server never replies the Transaction (for an unknown reason),
  691.      DoTransaction() can conceivably wait forever.
  692.  
  693.    BUGS
  694.  
  695.    SEE ALSO
  696.      BeginTransaction(), <envoy/nipc.h>
  697.  
  698. nipc.library/FindEntity                               nipc.library/FindEntity
  699.  
  700.    NAME
  701.      FindEntity -- Locate a specific entity on a certain host
  702.  
  703.    SYNOPSIS
  704.      remote_entity = FindEntity(hostname,entityname,src_entity,errorptr)
  705.            D0                      A0         A1        A2        A3
  706.  
  707.      struct Entity *FindEntity(STRPTR, STRPTR, struct Entity *,ULONG *);
  708.  
  709.    FUNCTION
  710.      Attempts to locate a certain entity on a given host.
  711.      If you pass a NULL for the entityname, FindEntity will
  712.      interpret that as "the local machine".
  713.  
  714.    INPUTS
  715.      hostname --   pointer to a null-terminated string declaring the
  716.                    host name of the machine on which you expect to
  717.                    find an Entity named the same as 'entityname'.
  718.  
  719.      entityname -- pointer to a null-terminated string declaring the
  720.                    name of a public entity.
  721.  
  722.      src_entity -- an Entity returned by CreateEntity() that you wish to
  723.                    use as the 'near' side of a communications path.
  724.  
  725.      errorptr   -- a pointer to a ULONG in which FindEntity() will provide
  726.                    detailed error information in the event of a FindEntity()
  727.                    failure.  If a NULL pointer is passed, no detailed error
  728.                    information will be available.
  729.  
  730.    RESULT
  731.      remote_entity --
  732.         NULL if the given Entity cannot be found.
  733.         Otherwise, the magic cookie describing the Entity that you found.
  734.  
  735.    EXAMPLE
  736.  
  737.    NOTES
  738.      If you do a FindEntity to a different machine and it succeeds,
  739.      you have no guarantee that the remote machine's Entity will
  740.      continue to exist.  Because of this, you should check all returned
  741.      Transactions for error status - if a Transaction to a remote
  742.      Entity fails because the nipc.library can no longer find the remote
  743.      Entity, the transaction will be returned as errored.
  744.      Regardless of what happens, every SUCCESSFUL FindEntity() REQUIRES an
  745.      associated LoseEntity().
  746.  
  747.      Since the FindEntity() establishes a communications link between
  748.      the source and destination Entities, it's -dependant- on the
  749.      source.  Therefore, do not DeleteEntity() the source entity before
  750.      LoseEntity()'ing.
  751.  
  752.    BUGS
  753.  
  754.    SEE ALSO
  755.      LoseEntity()
  756.  
  757. nipc.library/FreeNIPCBuff                           nipc.library/FreeNIPCBuff
  758.  
  759.    NAME
  760.      FreeNIPCBuff -- Free a NIPCBuff structure
  761.  
  762.    SYNOPSIS
  763.      FreeNIPCBuff(buff)
  764.                   A0
  765.  
  766.      VOID FreeNIPCBuff(struct NIPCBuff *);
  767.  
  768.    FUNCTION
  769.      This function is used to free a NIPCBuff structure and any
  770.      NIPCBuffEntry structures contained in it.  Note that the data areas
  771.      refereced by the NIPCBuffEntry's will not be freed.
  772.  
  773.    INPUTS
  774.      buff - Pointer to the NIPCBuf structure to be freed.
  775.  
  776.    RESULT
  777.      None
  778.  
  779.    EXAMPLE
  780.  
  781.    NOTES
  782.      You MUST use this function for freeing NIPCBuff structures, or
  783.      memory loss will occur.
  784.  
  785.    BUGS
  786.  
  787.    SEE ALSO
  788.        AllocNIPCBuff(), <envoy/nipc.h>
  789.  
  790. nipc.library/FreeNIPCBuffEntry                 nipc.library/FreeNIPCBuffEntry
  791.  
  792.    NAME
  793.      FreeNIPCBuffEntry -- Free a NIPCBuffEntry structure
  794.  
  795.    SYNOPSIS
  796.      FreeNIPCBuffEntry(entry)
  797.                        A0
  798.  
  799.      VOID FreeNIPCBuffEntry(struct NIPCBuffEntry *);
  800.  
  801.    FUNCTION
  802.      This function is used to free a NIPCBuffEntry structure.  Note that
  803.      the data area referenced by the NIPCBuffEntry structure will not be
  804.      freed.
  805.  
  806.    INPUTS
  807.      entry - Pointer to the NIPCBuffEntry structure to be freed.
  808.  
  809.    RESULT
  810.      None
  811.  
  812.    EXAMPLE
  813.  
  814.    NOTES
  815.      You MUST use this function for freeing NIPCBuffEntry structures, or
  816.      memory loss will occur.
  817.  
  818.    BUGS
  819.  
  820.    SEE ALSO
  821.        AllocNIPCBuffEntry(), <envoy/nipc.h>
  822.  
  823. nipc.library/FreeTransaction                     nipc.library/FreeTransaction
  824.  
  825.    NAME
  826.      FreeTransaction -- Free a previously allocated Transaction structure.
  827.  
  828.    SYNOPSIS
  829.      FreeTransaction(transaction)
  830.                           A1
  831.  
  832.      VOID FreeTransaction(struct Transaction *);
  833.  
  834.    FUNCTION
  835.      Transaction structures created by AllocTransaction() (which ought be
  836.      ALL of them), must be deallocated with FreeTransaction().
  837.      FreeTransaction() frees only the Transaction structure and any
  838.      portions of the structure that were allocated by the AllocTransaction()
  839.      function.
  840.  
  841.    INPUTS
  842.      transaction - a pointer to the Transaction structure to free
  843.                    if NULL, no action is taken.
  844.  
  845.    RESULT
  846.      None.
  847.  
  848.    EXAMPLE
  849.  
  850.    NOTES
  851.      Don't try to free anything that wasn't allocated by AllocTransaction().
  852.  
  853.    BUGS
  854.  
  855.    SEE ALSO
  856.      AllocTransactionA()
  857.  
  858. nipc.library/GetEntityAttrsA                     nipc.library/GetEntityAttrsA
  859.  
  860.    NAME
  861.      SetEntityAttrsA -- request the attributes of an Entity.  (37.106)
  862.      SetEntityAttrs -- varargs stub for GetEntityAttrsA().  (37.106)
  863.  
  864.    SYNOPSIS
  865.      numProcessed = GetEntityAttrsA(entity, tagList)
  866.                                       A0       A1
  867.  
  868.      ULONG GetEntityAttrsA(struct Entity *, struct TagItem *);
  869.  
  870.      numProcessed = GetEntityAttrs(entity, firsttag, ...)
  871.  
  872.      ULONG GetEntityAttrs(struct Entity *, Tag, ...);
  873.  
  874.    FUNCTION
  875.      Retrieve the attributes of a specified Entity, according to
  876.      the attributes chosen in the tag list.  For each entry in the
  877.      tag list, ti_Tag indentifies the attribute, and ti_Data is a
  878.      pointer to the long variable where you wish the result to be
  879.      stored.
  880.  
  881.    INPUTS
  882.      entity    - An Entity, created by CreateEntityA()
  883.      tagList   - pointer to an array of tags.
  884.  
  885.    TAGS
  886.      ENT_NameLength - Declare the size of your ENT_Name buffer.
  887.                       (MUST be in the same taglist as ENT_Name!)
  888.  
  889.      ENT_Name  -   Find the name of an Entity; ti_Data points to an
  890.                    ENT_NameLength sized buffer.  Cannot be used
  891.                    without ENT_NameLength.
  892.  
  893.      ENT_Public -  Determine whether an Entity is Public or
  894.                    not.  (TRUE implies PUBLIC, FALSE implies
  895.                    PRIVATE.)
  896.  
  897.      ENT_Signal -  Determine what signal bit (if any) is attached
  898.                    to the given Entity.  (-1 implies "none",
  899.                    other signal bit number is stored in the long
  900.                    pointed to by ti_Data.)
  901.  
  902.    RESULT
  903.  
  904.      numProcessed - the number of attributes successfully filled in.
  905.  
  906.    NOTES
  907.      Attributes not included in the above taglist are unreadable.
  908.      This function exists only in revision 37.106 and later.
  909.  
  910.    SEE ALSO
  911.      SetEntityAttrsA()
  912.  
  913. nipc.library/GetEntityName                         nipc.library/GetEntityName
  914.  
  915.    NAME
  916.      GetEntityName -- Get the ASCII name associated with an Entity.
  917.  
  918.    SYNOPSIS
  919.      status = GetEntityName(entity,stringptr,available);
  920.                               A0      A1        D0
  921.  
  922.      BOOL GetEntityName(STRPTR, STRPTR, ULONG);
  923.  
  924.    FUNCTION
  925.      Given a pointer to a string, the length of the string data area, and an
  926.      entity magic-cookie, this function will attempt to return the name
  927.      associated with the Entity.
  928.  
  929.    INPUTS
  930.      entity    - A magic cookie, identifying an Entity.
  931.      stringptr - A pointer to a section of memory that you'd like the name
  932.                  copied into.
  933.      available - The size of the above string area.
  934.  
  935.    RESULT
  936.      status    - Either TRUE or FALSE.  Note that even if you've
  937.                  referenced an entity, over a network - it's
  938.                  possible that resolving what the correct name
  939.                  is COULD fail.
  940.  
  941.    EXAMPLE
  942.  
  943.    NOTES
  944.      If the given Entity has no name, the string "UNNAMED ENTITY" will
  945.      be returned.
  946.  
  947.    BUGS
  948.  
  949.    SEE ALSO
  950.  
  951.  
  952. nipc.library/GetHostName                             nipc.library/GetHostName
  953.  
  954.    NAME
  955.      GetHostName -- Get the name of a specific machine.
  956.  
  957.    SYNOPSIS
  958.      status = GetHostName(entity,stringptr,available)
  959.        D0                   A0       A1        D0
  960.  
  961.      BOOL GetHostName(struct Entity *, STRPTR, ULONG);
  962.  
  963.    FUNCTION
  964.      Given a pointer to a string, the length of the string data area, and an
  965.      Entity magic-cookie, this function will attempt to return the ASCII
  966.      name associated with the host that the Entity is on.
  967.  
  968.    INPUTS
  969.      entity    - A magic cookie, identifying an Entity.
  970.                  (If NULL, the string returned will be either
  971.                   LocalRealm:LocalHost, or simply LocalHost -- depending on
  972.                   whether the local machine is in a realm-based environment
  973.                   or not.)
  974.  
  975.      stringptr - A pointer to a section of memory that you'd like the name
  976.                  copied into.
  977.      available - The size of the above string area.
  978.  
  979.    RESULT
  980.      status    - Either TRUE or FALSE.  Note that even if you've referenced
  981.                  an Entity over a network, it's possible that resolving
  982.                  the name COULD fail.
  983.  
  984.    EXAMPLE
  985.  
  986.    NOTES
  987.  
  988.    BUGS
  989.      Prior to version 40.9, GetHostName() would actually append LocalHost
  990.      to the buffer stringptr if a NULL entity was passed. Workaround:
  991.      Put an initial null byte into the buffer before calling this function.
  992.  
  993.    SEE ALSO
  994.  
  995. nipc.library/GetTransaction                       nipc.library/GetTransaction
  996.  
  997.    NAME
  998.      GetTransaction -- receive the next Transaction waiting on an Entity
  999.  
  1000.    SYNOPSIS
  1001.      transaction = GetTransaction(entity)
  1002.        D0                           A0
  1003.  
  1004.      struct Transaction *GetTransaction(struct Entity *);
  1005.  
  1006.    FUNCTION
  1007.      GetTransaction() attempts to remove the next available Transaction
  1008.      from the given Entity.
  1009.  
  1010.    INPUTS
  1011.      entity  -- An entity created by CreateEntity().  (Not from
  1012.                 FindEntity() as you're NOT allowed to read from
  1013.                 someone else's Entity.)
  1014.  
  1015.    RESULT
  1016.      transaction   --
  1017.                  NULL if no Transactions are waiting,
  1018.                  a pointer to a Transaction structure otherwise.
  1019.  
  1020.    EXAMPLE
  1021.  
  1022.    NOTES
  1023.      After a successful GetTransaction(), you should check the trans_Type
  1024.      field of a transaction to determine whether it's a request, or a
  1025.      returned failed request/response that was previously
  1026.      BeginTransaction()'d from this Entity.
  1027.  
  1028.      A transaction returned by GetTransaction will have TYPE_SERVICING
  1029.      for a request. Do not confuse this with TYPE_REQUEST!
  1030.  
  1031.      WARNING: Note that nipc.library might change how the transaction
  1032.      data was packed on the transfer. You MUST check if the request
  1033.      and response data buffers are NIPC buffers or not _before_
  1034.      referencing them. Check the trans_Flags field for this.
  1035.  
  1036.      Important: While nipc.library will not break any data from the source
  1037.                 entity into smaller pieces, it may combine them into
  1038.                 larger pieces. So if you find that the data is now an NIPC
  1039.                 buffer, you must use NIPCBuffPointer() to find the start
  1040.                 of your data chunks.
  1041.  
  1042.      Don't make any further assumptions. Just adhere to these rules and
  1043.      you should be safe.
  1044.  
  1045.  
  1046.    BUGS
  1047.  
  1048.    SEE ALSO
  1049.      BeginTransaction(), DoTransaction(), WaitTransaction(),
  1050.      ReplyTransaction(), NIPCBuffPointer(), <envoy/nipc.h>
  1051.  
  1052. nipc.library/LoseEntity                               nipc.library/LoseEntity
  1053.  
  1054.    NAME
  1055.      LoseEntity -- Free up any resources attached from a FindEntity.
  1056.  
  1057.    SYNOPSIS
  1058.      LoseEntity(entity)
  1059.                   A0
  1060.  
  1061.      VOID LoseEntity(struct Entity *);
  1062.  
  1063.    FUNCTION
  1064.      This will merely free up any resources allocated with a
  1065.      successful FindEntity() call.
  1066.  
  1067.    INPUTS
  1068.      entity      - An abstract data type - a "magic cookie" - that
  1069.                    identifies an Entity.  NULL for no action.
  1070.    RESULT
  1071.      None.
  1072.  
  1073.    EXAMPLE
  1074.  
  1075.    NOTES
  1076.      LoseEntity() should only be used on Entities returned by FindEntity().
  1077.  
  1078.  
  1079.    BUGS
  1080.  
  1081.    SEE ALSO
  1082.      CreateEntity(), DeleteEntity()
  1083.  
  1084. nipc.library/NIPCBuffLength                       nipc.library/NIPCBuffLength
  1085.  
  1086.    NAME
  1087.      NIPCBuffLength -- Determine the amount of data stored in a NIPCBuff
  1088.  
  1089.    SYNOPSIS
  1090.      length = NIPCBuffLength(buff)
  1091.      D0                      A0
  1092.  
  1093.      ULONG NIPCBuffLength(struct NIPCBuff *);
  1094.  
  1095.    FUNCTION
  1096.      This function may be used to determine the total amount of data stored
  1097.      in the NIPCBuff structure.  Note that this does not return the total
  1098.      capacity of all of the NIPCBuffEntry's.
  1099.  
  1100.    INPUTS
  1101.      buff - Pointer to a NIPCBuf structure
  1102.  
  1103.    RESULT
  1104.      length - Number of bytes stored in buff.
  1105.  
  1106.    EXAMPLE
  1107.  
  1108.    NOTES
  1109.  
  1110.    BUGS
  1111.  
  1112.    SEE ALSO
  1113.      <envoy/nipc.h>
  1114.  
  1115. nipc.library/NIPCBuffPointer                     nipc.library/NIPCBuffPointer
  1116.  
  1117.    NAME
  1118.      NIPCBuffPointer -- Get a pointer to data inside a NIPCBuff
  1119.  
  1120.    SYNOPSIS
  1121.      data = NIPCBuffPointer(buff, buffentry, offset)
  1122.      D0                     A0    A1         D0
  1123.  
  1124.      UBYTE *NIPCBuffPointer(struct NIPCBuff *, struct NIPCBuffEntry **,
  1125.                             ULONG);
  1126.  
  1127.    FUNCTION
  1128.      This function may be used to find a particular piece of data within a
  1129.      NIPCBuff structure.  Returns a pointer to the data item, and a pointer
  1130.      to the NIPCBuffEntry that contains that item.
  1131.  
  1132.    INPUTS
  1133.      buff - Pointer to a NIPCBuf structure
  1134.      offset - Offset into the NIPCBuff
  1135.      buffentry - Pointer to a struct NIPCBuffEntry * to be modified
  1136.  
  1137.    RESULT
  1138.      data - Points to the byte at offset bytes into buff.
  1139.      buffentry - Points to the NIPCBuffEntry that contains "data".
  1140.  
  1141.    EXAMPLE
  1142.  
  1143.    NOTES
  1144.  
  1145.    BUGS
  1146.  
  1147.      Versions of nipc.library prior to 40.7 had a problem with offsets
  1148.      that exactly matched the length of a BuffEntry, and returned a pointer
  1149.      past the end of the BuffEntry previous to the one it should have.
  1150.  
  1151.      Earlier autodocs had the offset and buffentry arguments reversed. This
  1152.      autodoc matches the published function prototype now.
  1153.  
  1154.    SEE ALSO
  1155.      <envoy/nipc.h>
  1156.  
  1157. nipc.library/NIPCInquiryA                           nipc.library/NIPCInquiryA
  1158.  
  1159.    NAME
  1160.        NIPCInquiryA -- Start a nipc network query
  1161.  
  1162.    SYNOPSIS
  1163.        success=NIPCInquiryA(hook, maxTime, maxResponses, tagList)
  1164.        D0                   A0    D0       D1            A1
  1165.  
  1166.        BOOL NIPCInquiryA(struct Hook *, ULONG, ULONG, APTR);
  1167.  
  1168.        success=NIPCInquiry(hook, maxTime, maxResponses, firsttag, ...)
  1169.  
  1170.        BOOL NIPCInquiry(struct Hook *, ULONG, ULONG, Tag, ...);
  1171.  
  1172.    FUNCTION
  1173.        Starts an NIPC Network Inquiry.  This function can be used to gather
  1174.        data about a single machine, or to gather data for a number of
  1175.        machines.  Multiple types of inquiries may be made using this
  1176.        function.  Please see below for a description of the types of queries
  1177.        and the types of information you may gather.
  1178.  
  1179.        The Hook is called for each packet returned from hosts on the
  1180.        network.  Depending on how specific your query is, you may or may
  1181.        not get more than one packet.  When either maxTime seconds or
  1182.        maxResponses packets have been received, your Hook will be called
  1183.        with a null ParamPckt parameter.  If your Hook routine decides that
  1184.        it has all of the information it needs, it may return FALSE.  This
  1185.        will cause nipc.library to abort the NIPCInquiry() call.
  1186.  
  1187.        When the Hook is called, the "Object" parameter will be a pointer to
  1188.        the Task structure for the task or process that called the
  1189.        NIPCInquiryA() function.  This is useful if you want to signal the
  1190.        calling task when the query is complete.  The Hook "Message"
  1191.        parameter will be a pointer to an array of TagItem structures that
  1192.        contain the query response data from each responding host.
  1193.  
  1194.        If the query fails for some reason, either due to illegal parameters
  1195.        or to a lack of resources, NIPCInquiryA() will return FALSE. In this
  1196.        case, your Hook function will never be called, so be careful.
  1197.  
  1198.  
  1199.    INPUTS
  1200.  
  1201.        hook(struct Hook *)     - Pointer to a Hook structure to be called for
  1202.                                  each response.
  1203.        maxTime(ULONG)          - The maximum number of seconds allowed for
  1204.                                  the query.  This is the absolute maximum
  1205.                                  time allowed.  Nipc.library does not add
  1206.                                  anything to this value.
  1207.        maxResponses(ULONG)     - The maximum number of responses that you
  1208.                                  will accept from the network.
  1209.        tagList(struct TagItem *) - Pointer to an array of TagItem structures.
  1210.                                    below.
  1211.  
  1212.    TAGS
  1213.        The Tags currently defined for NIPCInquiryA() are:
  1214.  
  1215.        QUERY_IPADDR (ULONG) - This tag is used for querying a machine for
  1216.                               it's Network IP address.  Note:  This function
  1217.                               is provided purely for diagnostic purposes. Do
  1218.                               NOT depend on this tag being available in the
  1219.                               future.
  1220.        MATCH_IPADDR (ULONG) - Query a host with the specified IP address
  1221.                               address.  Please see the note above regarding
  1222.                               QUERY_IPADDR.
  1223.        QUERY_REALMS (STRPTR) - Query a realmserver for the names of all known
  1224.                                Realms.
  1225.        MATCH_REALM (STRPTR) - Only query hosts that are in a specific Realm.
  1226.        QUERY_HOSTNAME (STRPTR) - Query a host for it's name.
  1227.        MATCH_HOSTNAME (STRPTR) - Only query the host with the specified
  1228.                                  hostname.
  1229.        QUERY_SERVICES (STRPTR) - Query a host or hosts for the names of all
  1230.                                  services on each machine.
  1231.        MATCH_SERVICE (STRPTR) - Only query hosts that have a specific service
  1232.                                 specified by the Tag.
  1233.        QUERY_ENTITIES (STRPTR) - Query a host or hosts for the names of all
  1234.                                  public entities on each machine.
  1235.        MATCH_ENTITY (STRPTR) - Query only hosts that have a public entity
  1236.                                specified by the Tag.
  1237.        QUERY_OWNER (STRPTR) - This Tag is currently ignored.
  1238.        MATCH_OWNER (STRPTR) - This Tag is currently ignored.
  1239.        QUERY_ATTNFLAGS (ULONG) - This Tag allows you to find out what bits
  1240.                                  are set in ExecBase->AttnFlags.
  1241.        MATCH_ATTNFLAGS (ULONG) - Query only hosts that have the specified
  1242.                                  bits set in ExecBase->AttnFlags.
  1243.        QUERY_LIBVERSION (VOID) - This Tag is currently ignored.
  1244.        MATCH_LIBVERSION (VOID) - This Tag is currently ignored.
  1245.        QUERY_CHIPREVBITS (ULONG) - This Tag alllows you to find out what
  1246.                                    bits are set in GfxBase->ChipRevBits0.
  1247.                                    Note: Only the lower 8 bits of the ULONG
  1248.                                    are used.
  1249.        MATCH_CHIPREVBITS (ULONG) - Query only hosts that have the specified
  1250.                                    bits set in GfxBase->ChipRevBits0.
  1251.        QUERY_MAXFASTMEM (ULONG) - Query a machine for it's maximum amount
  1252.                                   of FAST memory.
  1253.        MATCH_MAXFASTMEM (ULONG) -  Query only hosts with at least the
  1254.                                    specified amount of FAST memory.
  1255.        QUERY_AVAILFASTMEM (ULONG) - Query a machine for the amount of free
  1256.                                     FAST memory it has available.
  1257.        MATCH_AVAILFASTMEM (ULONG) - Query only those hosts that have at
  1258.                                     least the specified amount of FAST
  1259.                                     memory available.
  1260.        QUERY_MAXCHIPMEM (ULONG) - Query a machine for it's maximum amount
  1261.                                   of installed CHIP memory.
  1262.        MATCH_MAXCHIPMEM (ULONG) - Query only those hosts that have at least
  1263.                                   the specified amount of CHIP ram installed.
  1264.        QUERY_AVAILCHIPMEM (ULONG) - Query a machine for the amount of free
  1265.                                     CHIP memory it has available.
  1266.        MATCH_AVAILCHIPMEM (ULONG) - Query only those hosts that have at
  1267.                                     least the specified amount of CHIP
  1268.                                     memory available.
  1269.        QUERY_KICKVERSION (ULONG) - Query a machine for the version and
  1270.                                    revision of Kickstart it is running.
  1271.        MATCH_KICKVERSION (ULONG) - Query only those hosts that are running
  1272.                                    at least the specified version and
  1273.                                    revision of Kickstart.
  1274.        QUERY_WBVERSION (ULONG) - Query a machine for the version and
  1275.                                  revision of Workbench it is running.
  1276.        MATCH_WBVERSION (ULONG) - Query only those hosts that are running
  1277.                                  at least the specified version and revision
  1278.                                  of Workbench.
  1279.    RESULT
  1280.        success - Success/failure indication.
  1281.  
  1282.    EXAMPLES
  1283.  
  1284.        Query all hosts in realm "Software" for their Hostname, CPU type, Fast
  1285.        memory installed and Kickstart version:
  1286.  
  1287.        NIPCInquiry(myhook,             \* The hook to call *\
  1288.                    2,                  \* 2 seconds max *\
  1289.                    15,                 \* 15 responses max *\
  1290.                    MATCH_REALM,"Software",
  1291.                    QUERY_HOSTNAME, 0,
  1292.                    QUERY_ATTNFLAGS, 0,
  1293.                    QUERY_MAXFASTMEM, 0,
  1294.                    QUERY_KICKVERSION, 0,
  1295.                    TAG_DONE);
  1296.  
  1297.        The Hook would then get called for each host that responds. An example
  1298.        TagList passed to the hook might be:
  1299.  
  1300.                MATCH_REALM,"Software",
  1301.                QUERY_HOSTNAME,"A2500 Test".
  1302.                QUERY_ATTNFLAGS, AFF_68010|AFF_68020|AFF_68881,
  1303.                QUERY_MAXFASTMEM, 4194304,      (4 Megs)
  1304.                QUERY_KICKVERSION, 2425007,     (VERSION <<16 | REVISION)
  1305.                TAG_DONE
  1306.  
  1307.        ---
  1308.        Query a server for all services it has available
  1309.  
  1310.        NIPCInquiry(myhook,
  1311.                    2,
  1312.                    2,
  1313.                    MATCH_REALM,"Marketing",
  1314.                    MATCH_HOSTNAME,"Market Server",
  1315.                    QUERY_SERVICES,0,
  1316.                    TAG_DONE)
  1317.  
  1318.        A possible response might be:
  1319.  
  1320.                    MATCH_REALM,"Marketing",
  1321.                    MATCH_HOSTNAME,"Market Server",
  1322.                    QUERY_SERVICES,"EnvoyFileSystem",
  1323.                    QUERY_SERVICES,"EnvoyPrinterService",
  1324.                    QUERY_SERVICES,"ConferenceService",
  1325.                    TAG_DONE)
  1326.  
  1327.  
  1328.    NOTES
  1329.        This function is considered very low-level and is provided for network
  1330.        diagnostic functions.  You should probably be using the functions
  1331.        supplied in envoy.library to do network queries.  These will provide
  1332.        "wrappers" for the most common types of queries.
  1333.  
  1334. nipc.library/PingEntity                               nipc.library/PingEntity
  1335.  
  1336.    NAME
  1337.      PingEntity -- Calculate the round-trip time between two Entities
  1338.  
  1339.    SYNOPSIS
  1340.      elapsedtime = PingEntity(entity, limit)
  1341.        D0                       A0     D0
  1342.  
  1343.      ULONG PingEntity(struct Entity *, ULONG);
  1344.  
  1345.    FUNCTION
  1346.  
  1347.  
  1348.    INPUTS
  1349.      entity    - A magic cookie, identifying an Entity.
  1350.      limit     - Maximum number of microseconds to wait for a response.
  1351.  
  1352.    RESULT
  1353.      elapsedtime -
  1354.                  Total number of microseconds elapsed between attempting
  1355.                  to query the Entity, and a response returning.  If -1L,
  1356.                  no response was received in the given timeout interval.
  1357.                  Local Entities will return 0 for elapsed time.
  1358.  
  1359.    EXAMPLE
  1360.  
  1361.    NOTES
  1362.  
  1363.    BUGS
  1364.  
  1365.    SEE ALSO
  1366.  
  1367. nipc.library/ReplyTransaction                   nipc.library/ReplyTransaction
  1368.  
  1369.    NAME
  1370.      ReplyTransaction -- Reply a Transaction.
  1371.  
  1372.    SYNOPSIS
  1373.      ReplyTransaction(transaction)
  1374.                            A1
  1375.  
  1376.      VOID ReplyTransaction(struct Transaction *);
  1377.  
  1378.    FUNCTION
  1379.      This causes a Transaction received from another Entity to be
  1380.      returned to the sender.  You may return data with the
  1381.      Transaction as well.  (See the Transaction structure
  1382.      definition for details.)
  1383.  
  1384.    INPUTS
  1385.      transaction -- Pointer to a Transaction structure that was
  1386.                     returned by a previous GetTransaction() call.
  1387.  
  1388.    RESULT
  1389.      None.
  1390.  
  1391.    EXAMPLE
  1392.  
  1393.    NOTES
  1394.  
  1395.    BUGS
  1396.  
  1397.    SEE ALSO
  1398.        GetTransaction()
  1399.  
  1400. nipc.library/SetEntityAttrsA                     nipc.library/SetEntityAttrsA
  1401.  
  1402.    NAME
  1403.      SetEntityAttrsA -- change the attributes of an Entity.  (37.106)
  1404.      SetEntityAttrs -- varargs stub for SetEntityAttrsA().  (37.106)
  1405.  
  1406.    SYNOPSIS
  1407.      SetEntityAttrsA(entity, tagList)
  1408.                        A0       A1
  1409.  
  1410.      VOID SetEntityAttrsA(struct Entity *, struct TagItem *);
  1411.  
  1412.      SetEntityAttrs(entity, firsttag, ...)
  1413.  
  1414.      VOID SetEntityAttrs(struct Entity *, Tag, ...);
  1415.  
  1416.    FUNCTION
  1417.      Change the attributes of a specified Entity, according to
  1418.      the attributes chosen in the tag list.  If an attribute is
  1419.      not provided in the tag list, it's value remains unchanged.
  1420.  
  1421.    INPUTS
  1422.      entity    - An Entity, created by CreateEntityA()
  1423.      tagList   - pointer to an array of tags providing optional
  1424.                  extra parameters, or NULL.
  1425.    TAGS
  1426.      ENT_Public -   Set/Reset the public state of an Entity.
  1427.                     TRUE = PUBLIC, FALSE = PRIVATE.
  1428.  
  1429.      ENT_Release -  Refuse ownership of this Entity; deallocates
  1430.                     any signal bits created with ENT_AllocSignal.
  1431.                     (Not those passed in with ENT_Signal!)
  1432.                     Use in conjunction with ENT_Inherit to pass an
  1433.                     Entity between processes.
  1434.  
  1435.      ENT_Inherit -  Declares ownership of an Entity that has
  1436.                     previously been set with ENT_Release.
  1437.                     If a signal bit is necessary, this call should
  1438.                     be used with ENT_Signal or ENT_AllocSignal.
  1439.  
  1440.      ENT_Signal  -  Set the signal bit of the Entity to the bit
  1441.                     value specified by ti_Data.  If a bit was
  1442.                     previously allocated by ENT_AllocSignal, it
  1443.                     will be freed.
  1444.  
  1445.      ENT_AllocSignal -
  1446.                     Allocate a signal bit for this Entity.
  1447.                     ti_Data points to a longword where you
  1448.                     wish the bit number to be stored, or NULL.
  1449.                     If a signal bit was previously allocated
  1450.                     by ENT_AllocSignal, it will be freed,
  1451.                     regardless of the success/failure of this
  1452.                     attribute modification.
  1453.  
  1454.      ENT_TimeoutLinks -
  1455.                     Defines that any link entities connected
  1456.                     to this Entity should be automatically
  1457.                     removed after ti_Data seconds of inactivity.
  1458.                     0 seconds is defined as meaning "infinite"
  1459.                     timeouts, which is the default on
  1460.                     Entity creation.
  1461.  
  1462.    NOTES
  1463.      Attributes not included in the above taglist are unchangable.
  1464.      This function exists only in revision 37.106 and later.
  1465.  
  1466.    SEE ALSO
  1467.      GetEntityAttrsA()
  1468.  
  1469. nipc.library/WaitEntity                               nipc.library/WaitEntity
  1470.  
  1471.    NAME
  1472.      WaitEntity -- Waits for a Transaction to arrive at an Entity.
  1473.  
  1474.    SYNOPSIS
  1475.      WaitEntity(localentity)
  1476.                     A0
  1477.  
  1478.      VOID WaitEntity(struct Entity *);
  1479.  
  1480.    FUNCTION
  1481.      WaitEntity() simply causes the current process to Wait() until
  1482.      something arrives at the entity.
  1483.  
  1484.    INPUTS
  1485.      entity      - An abstract data type - a "magic cookie" - that
  1486.                    identifies an Entity.
  1487.  
  1488.    RESULT
  1489.      None.
  1490.  
  1491.    EXAMPLE
  1492.  
  1493.    NOTES
  1494.      This is potentially dangerous - if nothing ever arrives at this
  1495.      Entity, this function will never return.  Unless warrented,
  1496.      the caller should be using Wait() with a signal mask.
  1497.  
  1498.    BUGS
  1499.  
  1500.    SEE ALSO
  1501.      GetTransaction()
  1502.  
  1503. nipc.library/WaitTransaction                     nipc.library/WaitTransaction
  1504.  
  1505.    NAME
  1506.      WaitTransaction -- Waits for a Transaction to complete.
  1507.  
  1508.    SYNOPSIS
  1509.      WaitTransaction(transaction)
  1510.                           A1
  1511.  
  1512.      VOID WaitTransaction(struct Transaction *);
  1513.  
  1514.    FUNCTION
  1515.      Waits for the given transaction to complete, or return as failed.
  1516.  
  1517.    INPUTS
  1518.      transaction -- a pointer to a Transaction structure.
  1519.  
  1520.    RESULT
  1521.      None.
  1522.  
  1523.    EXAMPLE
  1524.  
  1525.    NOTES
  1526.      - When doing networked transactions, if for any reason the remote
  1527.        machine fails to send a response, (but no network problem exists)
  1528.        and you did not supply a timeout value in trans_Timeout,
  1529.        WaitTransaction() can Wait() forever.
  1530.  
  1531.      - If you attempt to WaitTransaction() on a transaction that has
  1532.        already been responded to, WaitTransaction() will return
  1533.        immediately.
  1534.  
  1535.      - If the given Transaction has not already completed, WaiTransaction()
  1536.        will wait for it to complete, and then -remove- the Transaction
  1537.        from the source Entity.  (In other words, you don't need to
  1538.        GetTransaction() it off of the Entity.)
  1539.  
  1540.    BUGS
  1541.  
  1542.    SEE ALSO
  1543.        BeginTransaction(), DoTransaction(), exec.library/Wait()
  1544.  
  1545.